---
description: Couchbase Lite Concepts — Data Model — Blobs
related_content:
  - name: Databases
    url: /databases
  - name: Documents
    url: /documents
  - name: Indexing
    url: /indexing
---

# Blobs

## Introduction

Couchbase Lite for Dart uses blobs to store the contents of images, other media
files and similar format files as binary objects.

The blob itself is not stored in the document. It is held in a separate
content-addressable store indexed from the document and retrieved only
on-demand.

When a document is synchronized, the Couchbase Lite replicator adds an
`_attachments` dictionary to the document's properties if it contains a blob
— see [Figure 1](#).

## Blob Objects

The blob as an object appears in a document as dictionary property — see, for
example _avatar_ in [Figure 1](#).

Other properties include `length` (the length in bytes), and optionally
`content_type` (typically, its MIME type).

The blob's data (an image, audio or video content) is not stored in the
document, but in a separate content-addressable store, indexed by the `digest`
property — see [Using Blobs](#using-blobs).

### Constraints

- Couchbase Lite <br /> Blobs can be arbitrarily large. They are only read on
  demand, not when you load a the document.

- Capella App Services/Sync Gateway <br /> The maximum content size is 20 MB per
  blob. If a document's blob is over 20 MB, the document will be replicated but
  not the blob.

## Using Blobs

The `api|Blob` API lets you access the blob's data content as in-memory data
(`api|dart:typed_data|Uint8List`) or as a `api|dart:async|Stream` of
`api|dart:typed_data|Uint8List`s.

The code in [Example 1](#) shows how you might add a blob to a document and save
it to the database. Here we use avatar as the property key and a jpeg file as
the blob data.

<CodeExample id={1} title="Working with Blobs">

```dart
final data = getAsset('avatar.jpg');
if (data == null) { return; }

final blob = Blob.fromData('image/jpeg', data);
doc.setBlob(blob, key: 'avatar');
await database.saveDocument(doc);

final image = doc.blob('avatar');
```

</CodeExample>

## Syncing

When a document containing a blob object is synchronized, the Couchbase Lite
replicator generates an `_attachments` dictionary with an auto-generated name
for each blob attachment. This is different to the `avatar` key and is used
internally to access the blob content.

If you view a sync'd blob document in either Capella's Admin Interface or
Couchbase Server's Admin Console, you will see something similar to
[Figure 1](#), which shows the document with its generated `_attachments`
dictionary, including the digest.

<Figure id={1} title="Sample Blob Document">

```json
{
  "_attachments": {
    "blob_1": {
      "content_type": "image/jpeg",
      "digest": "sha1-F1Tfe61RZP4zC9UYT6JFmLTh2s8=",
      "length": 8112955,
      "revpos": 2,
      "stub": true
    }
  },
  "avatar": {
    "@type": "blob",
    "content_type": "image/jpeg",
    "digest": "sha1-F1Tfe61RZP4zC9UYT6JFmLTh2s8=",
    "length": 8112955
  }
}
```

</Figure>
